---
title: Боковая панель
description: Узнайте, как установить и настроить навигационные ссылки в боковой панели сайта Starlight.
---

import { FileTree } from '@astrojs/starlight/components';
import SidebarPreview from '~/components/sidebar-preview.astro';

Хорошо организованная боковая панель — ключ к хорошей документации, поскольку это один из основных способов навигации пользователей по вашему сайту. Starlight предоставляет полный набор опций для настройки макета и содержимого боковой панели.

## Стандартная боковая панель

По умолчанию Starlight автоматически генерирует боковую панель на основе структуры файловой системы вашей документации, используя свойство `title` каждого файла в качестве элемента боковой панели.

Например, при следующей структуре файлов:

<FileTree>

- src/
  - content/
    - docs/
      - constellations/
        - andromeda.md
        - orion.md
      - stars/
        - betelgeuse.md

</FileTree>

Будет автоматически сгенерирована следующая боковая панель:

<SidebarPreview
	config={[
		{
			label: 'constellations',
			items: [
				{ label: 'Андромеда', link: '' },
				{ label: 'Орион', link: '' },
			],
		},
		{
			label: 'stars',
			items: [{ label: 'Бетельгейзе', link: '' }],
		},
	]}
/>

Узнайте больше об автоматически генерируемых боковых панелях в разделе [Автогенерируемые группы](#автогенерируемые-группы).

## Добавление ссылок и групп ссылок

Чтобы настроить ссылки и группы ссылок на боковой панели (внутри сворачиваемого заголовка), используйте свойство [`starlight.sidebar`](/ru/reference/configuration/#sidebar) в `astro.config.mjs`.

Комбинируя ссылки и группы, вы можете создавать разнообразные макеты боковой панели.

### Внутренние ссылки

Добавьте ссылку на страницу в `src/content/docs/`, используя объект со свойством `slug`.
Заголовок связанной страницы будет использоваться в качестве метки по умолчанию.

Например, со следующей конфигурацией:

```js "slug:"
starlight({
	sidebar: [
		{ slug: 'constellations/andromeda' },
		{ slug: 'constellations/orion' },
	],
});
```

И следующей файловой структурой:

<FileTree>

- src/
  - content/
    - docs/
      - constellations/
        - andromeda.md
        - orion.md

</FileTree>

Будет создана следующая боковая панель:

<SidebarPreview
	config={[
		{ label: 'Андромеда', link: '' },
		{ label: 'Орион', link: '' },
	]}
/>

Чтобы переопределить значения, полученные из метаданных связанной страницы, вы можете добавить свойства `label`, [`translations`](#интернационализация) и [`attrs`](#пользовательские-html-атрибуты).

См. [Настройка сгенерированных ссылок](#настройка-сгенерированных-ссылок-через-метаданные) для получения более подробной информации об управлении внешним видом боковой панели из метаданных страницы.

#### Сокращенное обозначение внутренних ссылок

Внутренние ссылки также можно определить, указав только строку для обозначения страницы в качестве сокращения.

Например, следующая конфигурация эквивалентна конфигурации выше, в которой используется `slug`:

```js "slug:"
starlight({
	sidebar: ['constellations/andromeda', 'constellations/orion'],
});
```

### Другие ссылки

Добавьте ссылку на внешнюю страницу или страницу, не являющуюся документацией, используя объект со свойствами `label` и `link`.

```js "label:" "link:"
starlight({
	sidebar: [
		// Ссылка на страницу, не связанную с документацией, на этом сайте.
		{ label: 'Meteor Store', link: '/shop/' },
		// Внешняя ссылка на веб-сайт NASA.
		{ label: 'NASA', link: 'https://www.nasa.gov/' },
	],
});
```

Конфигурация выше создаёт следующую боковую панель:

<SidebarPreview
	config={[
		{ label: 'Meteor Store', link: '' },
		{ label: 'NASA', link: 'https://www.nasa.gov/' },
	]}
/>

### Группы

Вы можете структурировать вашу боковую панель, группируя связанные ссылки вместе под раскрывающимся заголовком.
Группы могут содержать как ссылки, так и другие подгруппы.

Добавьте группу, используя объект со свойствами `label` и `items`.
`label` будет использован как заголовок для группы.
Добавляйте ссылки или подгруппы в массив `items`.

```js /^\s*(label:|items:)/
starlight({
	sidebar: [
		// Группа ссылок с названием «Созвездия».
		{
			label: 'Созвездия',
			items: [
				'constellations/carina',
				'constellations/centaurus',
				// Вложенная группа ссылок для сезонных созвездий.
				{
					label: 'Сезонные',
					items: [
						'constellations/andromeda',
						'constellations/orion',
						'constellations/ursa-minor',
					],
				},
			],
		},
	],
});
```

Вышеуказанная конфигурация генерирует следующую боковую панель:

<SidebarPreview
	config={[
		{
			label: 'Созвездия',
			items: [
				{ label: 'Карина', link: '' },
				{ label: 'Центавр', link: '' },
				{
					label: 'Сезонные',
					items: [
						{ label: 'Андромеда', link: '' },
						{ label: 'Орион', link: '' },
						{ label: 'Малая Медведица', link: '' },
					],
				},
			],
		},
	]}
/>

### Автогенерируемые группы

Starlight может автоматически генерировать группу в вашей боковой панели, основываясь на директориях в вашей документации.
Это полезно, когда вы не хотите вручную вводить каждый элемент боковой панели в группе.

По умолчанию страницы сортируются в алфавитном порядке в соответствии со свойством [`slug`](/ru/reference/route-data/#slug) или именем файла.

Добавьте автогенерируемую группу, используя объект со свойствами `label` и `autogenerate`. Ваша конфигурация `autogenerate` должна указывать `directory`, которая будет использоваться для записей боковой панели. Например, со следующей конфигурацией:

```js "label:" "autogenerate:"
starlight({
	sidebar: [
		{
			label: 'Созвездия',
			// Автогенерация группы ссылок для директории 'constellations'.
			autogenerate: { directory: 'constellations' },
		},
	],
});
```

И следующей структурой файлов:

<FileTree>

- src/
  - content/
    - docs/
      - constellations/
        - carina.md
        - centaurus.md
        - seasonal/
          - andromeda.md

</FileTree>

Будет сгенерирована следующая боковая панель:

<SidebarPreview
	config={[
		{
			label: 'Созвездия',
			items: [
				{ label: 'Карина', link: '' },
				{ label: 'Центавр', link: '' },
				{
					label: 'seasonal',
					items: [{ label: 'Андромеда', link: '' }],
				},
			],
		},
	]}
/>

## Настройка сгенерированных ссылок через метаданные

Используйте [поле `sidebar`](/ru/reference/frontmatter/#sidebar) в метаданных страниц для настройки автоматически генерируемых ссылок.

Параметры в метаданных для боковой панели позволяют установить [пользовательскую метку](/ru/reference/frontmatter/#label), использовать [пользовательские атрибуты](/ru/reference/frontmatter/#attrs), добавить [значок](/ru/reference/frontmatter/#badge) к ссылке, [скрыть](/ru/reference/frontmatter/#hidden) ссылку из боковой панели или определить [порядок её сортировки](/ru/reference/frontmatter/#order).

```md "sidebar:"
---
# src/content/docs/example.md
title: Моя страница
sidebar:
  # Установить текст для ссылки
  label: Текст в боковой панели
  # Установить порядок для ссылки (чем ниже число, тем выше будет отображаться ссылка)
  order: 2
  # Добавить значок к ссылке
  badge:
    text: Новое
    variant: tip
---
```

Автоматически созданная группа, включающая страницу с вышеуказанными метаданными, сгенерирует следующую боковую панель:

<SidebarPreview
	config={[
		{
			label: 'Руководства',
			items: [
				{ label: 'Моя страница', link: '' },
				{
					label: 'Текст в боковой панели',
					link: '',
					badge: { text: 'Новое', variant: 'tip' },
				},
				{ label: 'Другая страница', link: '' },
			],
		},
	]}
/>

:::note
Параметр `sidebar` в метаданных используется только для ссылок в автогенерируемых группах и ссылок на документы, заданных с помощью свойства `slug`. Он не применяется к ссылкам, заданным с помощью свойства `link`.
:::

## Значки

Ссылки также могут включать свойство `badge` для отображения значка рядом с текстом ссылки.

```js {9,16}
starlight({
	sidebar: [
		{
			label: 'Звёзды',
			items: [
				// Ссылка со значком «Сверхгигант».
				{
					slug: 'stars/persei',
					badge: 'Сверхгигант',
				},
			],
		},
		// Автогенерируемая группа со значком "Устарело".
		{
			label: 'Луны',
			badge: 'Устарело',
			autogenerate: { directory: 'moons' },
		},
	],
});
```

Конфигурация выше создаст следующую боковую панель:

<SidebarPreview
	config={[
		{
			label: 'Звёзды',
			items: [
				{
					label: 'Персей',
					link: '',
					badge: { text: 'Сверхгигант', variant: 'default' },
				},
			],
		},
		{
			label: 'Луны',
			badge: { text: 'Устарело', variant: 'default' },
			items: [
				{
					label: 'Ио',
					link: '',
				},
				{
					label: 'Европа',
					link: '',
				},
				{
					label: 'Ганимед',
					link: '',
				},
			],
		},
	]}
/>

### Варианты значков и индивидуальная стилизация

Настройте стиль значка, используя объект со свойствами `text`, `variant` и `class`.

`text` представляет содержимое для отображения (например, «Новое»).
По умолчанию значок будет использовать акцентный цвет вашего сайта. Чтобы использовать встроенный стиль значка, установите для свойства `variant` одно из следующих значений: `note`, `tip`, `danger`, `caution` или `success`.

Кроме того, можно создать собственный стиль значка, задав свойству `class` имя класса CSS.

```js {9}
starlight({
	sidebar: [
		{
			label: 'Звёзды',
			items: [
				// Ссылка с жёлтым значком «Заглушка»
				{
					slug: 'stars/sirius',
					badge: { text: 'Заглушка', variant: 'caution' },
				},
			],
		},
	],
});
```

Конфигурация выше создаст следующую боковую панель:

<SidebarPreview
	config={[
		{
			label: 'Звёзды',
			items: [
				{
					label: 'Сириус',
					link: '',
					badge: { text: 'Заглушка', variant: 'caution' },
				},
			],
		},
	]}
/>

Узнайте больше об [использовании и настройке значков](/ru/components/badges/#использование).

## Пользовательские HTML-атрибуты

Ссылки также могут включать свойство `attrs` для добавления пользовательских HTML-атрибутов к элементу ссылки.

В следующем примере `attrs` используется для добавления атрибута `target="_blank"`, чтобы ссылка открывалась в новой вкладке, а также для применения атрибута `style`, чтобы курсивом выделить метку ссылки:

```js {10}
starlight({
	sidebar: [
		{
			label: 'Ресурсы',
			items: [
				// Внешняя ссылка на сайт NASA, открывающаяся в новой вкладке.
				{
					label: 'NASA',
					link: 'https://www.nasa.gov/',
					attrs: { target: '_blank', style: 'font-style: italic' },
				},
			],
		},
	],
});
```

Конфигурация выше создаст следующую боковую панель:

<SidebarPreview
	config={[
		{
			label: 'Ресурсы',
			items: [
				{
					label: 'NASA',
					link: 'https://www.nasa.gov/',
					attrs: {
						target: '_blank',
						style: 'font-style: italic',
					},
				},
			],
		},
	]}
/>

### Пользовательские HTML-атрибуты для автоматически сгенерированных ссылок

Настройте HTML-атрибуты всех ссылок в [автоматически сгенерированных группах](#автогенерируемые-группы), указав свойство `attrs` в конфигурации `autogenerate`.
Отдельные страницы могут задавать пользовательские атрибуты с помощью поля [`sidebar.attrs`](/ru/reference/frontmatter/#attrs) в метаданных, которое будет объединено с конфигурацией `autogenerate.attrs`.

Например, со следующей конфигурацией:

```js {9}
starlight({
	sidebar: [
		{
			label: 'Созвездия',
			autogenerate: {
				// Автоматически генерируем группу ссылок для директории 'constellations'
				directory: 'constellations',
				// Выделяем курсивом все ярлыки ссылок в этой группе
				attrs: { style: 'font-style: italic' },
			},
		},
	],
});
```

и следующей файловой структурой:

<FileTree>

- src/
  - content/
    - docs/
      - constellations/
        - carina.md
        - centaurus.md
        - seasonal/
          - andromeda.md

</FileTree>

Будет сгенерирована боковая панель с выделением всех автоматически созданных ссылок курсивом:

<SidebarPreview
	config={[
		{
			label: 'Созвездия',
			items: [
				{ label: 'Карина', link: '', attrs: { style: 'font-style: italic' } },
				{
					label: 'Центавр',
					link: '',
					attrs: { style: 'font-style: italic' },
				},
				{
					label: 'seasonal',
					items: [
						{
							label: 'Андромеда',
							link: '',
							attrs: { style: 'font-style: italic' },
						},
					],
				},
			],
		},
	]}
/>

## Интернационализация

Используйте свойство `translations` для записей ссылок и групп, чтобы перевести метку ссылки или группы для каждого поддерживаемого языка, указав тег языка [BCP-47](https://www.w3.org/International/questions/qa-choosing-language-tags), например, `"en"`, `"ru"` или `"zh-CN"` в качестве ключа, и перевод метки — в качестве значения.
Свойство `label` будет использоваться для локали по умолчанию и для языков без перевода.

```js {5-7,11-13,18-20}
starlight({
	sidebar: [
		{
			label: 'Созвездия',
			translations: {
				'pt-BR': 'Constelações',
			},
			items: [
				{
					label: 'Андромеда',
					translations: {
						'pt-BR': 'Andrômeda',
					},
					slug: 'constellations/andromeda',
				},
				{
					label: 'Скорпион',
					translations: {
						'pt-BR': 'Escorpião',
					},
					slug: 'constellations/scorpius',
				},
			],
		},
	],
});
```

При просмотре документации на бразильском португальском языке будет сгенерирована следующая боковая панель:

<SidebarPreview
	config={[
		{
			label: 'Constelação',
			items: [
				{ label: 'Andrômeda', link: '' },
				{ label: 'Escorpião', link: '' },
			],
		},
	]}
/>

### Интернационализация с внутренними ссылками

[Внутренние ссылки](#внутренние-ссылки) по умолчанию будут автоматически использовать переведённые заголовки страниц из метаданных контента:

```js {9-10}
starlight({
	sidebar: [
		{
			label: 'Созвездия',
			translations: {
				'pt-BR': 'Constelações',
			},
			items: [
				{ slug: 'constellations/andromeda' },
				{ slug: 'constellations/scorpius' },
			],
		},
	],
});
```

При просмотре документации на бразильском португальском языке появится следующая боковая панель:

<SidebarPreview
	config={[
		{
			label: 'Constelações',
			items: [
				{ label: 'Andrômeda', link: '' },
				{ label: 'Escorpião', link: '' },
			],
		},
	]}
/>

На многоязычных сайтах значение `slug` не включает языковую часть URL.
Например, если у вас есть страницы `en/intro` и `pt-br/intro`, при настройке боковой панели в качестве slug будет `intro`.

### Интернационализация с помощью значков

Для [значков](#значки) свойство `text` может быть строкой, а для многоязычных сайтов — объектом со значениями для каждой локали.
При использовании объектной формы ключи должны быть тегами [BCP-47](https://www.w3.org/International/questions/qa-choosing-language-tags) (например: `en`, `ar` или `zh-CN`):

```js {11-16}
starlight({
	sidebar: [
		{
			label: 'Созвездия',
			translations: {
				'pt-BR': 'Constelações',
			},
			items: [
				{
					slug: 'constellations/andromeda',
					badge: {
						text: {
							ru: 'Новинка',
							'pt-BR': 'Novo',
						},
					},
				},
			],
		},
	],
});
```

При просмотре документации на бразильском португальском языке появится следующая боковая панель:

<SidebarPreview
	config={[
		{
			label: 'Constelações',
			items: [
				{
					label: 'Andrômeda',
					link: '',
					badge: { text: 'Novo', variant: 'default' },
				},
			],
		},
	]}
/>

## Сворачиваемые группы

Группы ссылок могут быть свёрнуты по умолчанию, если установить свойство `collapsed` в `true`.

```js {5-6}
starlight({
	sidebar: [
		{
			label: 'Созвездия',
			// Сворачивание группы по умолчанию
			collapsed: true,
			items: [
				items: ['constellations/andromeda', 'constellations/orion'],
			],
		},
	],
});
```

Конфигурация выше создает следующую боковую панель:

<SidebarPreview
	config={[
		{
			label: 'Созвездия',
			collapsed: true,
			items: [
				{ label: 'Андромеда', link: '' },
				{ label: 'Орион', link: '' },
			],
		},
	]}
/>

[Автогенерируемые группы](#автогенерируемые-группы) учитывают значение `collapsed` родительской группы:

```js {5-6}
starlight({
	sidebar: [
		{
			label: 'Созвездия',
			// Сворачивание группы и её автогенерируемых подгрупп по умолчанию.
			collapsed: true,
			autogenerate: { directory: 'constellations' },
		},
	],
});
```

Конфигурация выше создает следующую боковую панель:

<SidebarPreview
	config={[
		{
			label: 'Созвездия',
			collapsed: true,
			items: [
				{ label: 'Карина', link: '' },
				{ label: 'Центавр', link: '' },
				{
					label: 'seasonal',
					collapsed: true,
					items: [{ label: 'Андромеда', link: '' }],
				},
			],
		},
	]}
/>

Это поведение может быть переопределено путём установки свойства `autogenerate.collapsed`.

```js {5-7} "collapsed: true"
starlight({
	sidebar: [
		{
			label: 'Созвездия',
			// Не сворачивать группу «Созвездия», но сворачивать её
			// автоматически сгенерированные подгруппы.
			collapsed: false,
			autogenerate: { directory: 'constellations', collapsed: true },
		},
	],
});
```

Конфигурация выше создает следующую боковую панель:

<SidebarPreview
	config={[
		{
			label: 'Созвездия',
			items: [
				{ label: 'Карина', link: '' },
				{ label: 'Центавр', link: '' },
				{
					label: 'seasonal',
					collapsed: true,
					items: [{ label: 'Андромеда', link: '' }],
				},
			],
		},
	]}
/>
